home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
EnigmA Amiga Run 1996 March
/
EnigmA AMIGA RUN 05 (1996)(G.R. Edizioni)(IT)[!][issue 1996-03][Skylink CD IV].iso
/
earcd
/
util4
/
xfd111.lha
/
xfd
/
autodoc
/
xfdmaster.doc
Wrap
Text File
|
1996-02-04
|
34KB
|
1,009 lines
TABLE OF CONTENTS
xfdmaster.library/--Overview--
xfdmaster.library/xfdAllocBufferInfo
xfdmaster.library/xfdAllocObject
xfdmaster.library/xfdAllocSegmentInfo
xfdmaster.library/xfdDecrunchBuffer
xfdmaster.library/xfdDecrunchSegment
xfdmaster.library/xfdFreeBufferInfo
xfdmaster.library/xfdFreeObject
xfdmaster.library/xfdFreeSegmentInfo
xfdmaster.library/xfdGetErrorText
xfdmaster.library/xfdRecogBuffer
xfdmaster.library/xfdRecogLinker
xfdmaster.library/xfdRecogSegment
xfdmaster.library/xfdRelocate
xfdmaster.library/xfdStripHunks
xfdmaster.library/xfdTestHunkStructure
xfdmaster.library/xfdTestHunkStructureFlags
xfdmaster.library/xfdTestHunkStructureNew
xfdmaster.library/xfdUnlink
xfdForeman/--Overview--
xfdSlave/--Overview--
xfdSlave/RecogBufferXYZ
xfdSlave/DecrunchBufferXYZ
xfdSlave/RecogSegmentXYZ
xfdSlave/DecrunchSegmentXYZ
xfdmaster.library/--Overview-- xfdmaster.library/--Overview--
This section describes the usual way how to use xfdmaster.library from your
own applications.
If you want to decrunch files from a buffer, do it like this:
1. Call xfdAllocObject() with XFDOBJ_BUFFERINFO (V36). If not successful,
go on with 12.
2. Get file size, allocate buffer with that size and load file to buffer.
If not successful, go on with 10.
3. Call xfdRecogBuffer() with xfdbi_SourceBuffer and xfdbi_SourceBufLen
initialized. If not successful, file is not crunched and you may work
with that file as it is, release the used memory and go on with 10.
4. Check xfdbi_PackerFlags for XFDPFB_PASSWORD or XFDPFB_KEY16/32 (V35),
go on with 6. if not set.
5. Get password (maximum length is stored in xfdbi_MaxSpecialLen) or
the required 16/32 bit key and store a pointer to it in xfdbi_Special.
If xfdbi_MaxSpecialLen is -1 then password length is not limited.
6. Initialize xfdbi_TargetBufMemType and call xfdDecrunchBuffer(). If not
successful, work with crunched file, release memory afterwards and
go on with 10.
7. Release memory of xfdbi_SourceBuffer.
8. Work with decrunched file.
9. Release memory of xfdbi_TargetBuffer.
10. If you have another file to decrunch, step back to 2.
11. Call xfdFreeObject() (V36).
12. Exit!
If you want to decrunch a segment list, do it like this:
1. Call xfdAllocObject() with XFDOBJ_SEGMENTINFO (V36). If not successful,
go on with 11.
2. dos.library/LoadSeg() file. If not successful, go on with 9.
3. Call xfdRecogSegment() with xfdsi_SegList initialized. If not
successful, seglist isn't crunched and you may go on with 7.
4. Check xfdsi_PackerFlags for XFDPFB_PASSWORD or XFDPFB_KEY16/32 (V35).
If set, get password (maximum length is stored in xfdsi_MaxSpecialLen)
or 16/32 bit key and store a pointer to it in xfdsi_Special.
If xfdsi_MaxSpecialLen is -1 then password length is not limited.
5. (V34) Check xfdsi_PackerFlags for XFDPFB_RELMODE. If set, init
xfdsi_RelMode with the desired value.
6. Call xfdDecrunchSegment(). If not successful, test xfdsi_SegList.
If this field contains NULL, no seglist is available anymore. You
have to dos.library/LoadSeg() the file again then.
7. Work with segment list.
8. dos.library/UnloadSeg() segment list.
9. If you have another segment list to decrunch, step back to 2.
10. Call xfdFreeObject() (V36).
11. Exit!
If you only want to test if one or more files are crunched without
decrunching it afterwards, here's a way to do this:
1. Call xfdAllocObject() with XFDOBJ_BUFFERINFO (V36). If not successful,
go on with 9.
2. Get minimum buffer size for recognition from xfdm_MinBufferSize (V36),
allocate buffer with that size and initialize xfdbi_SourceBuffer
and xfdbi_SourceBufLen. On error goto 8.
3. Read as many bytes from the file as fit in xfdbi_SourceBuffer.
If file is shorter than xfdm_MinBufferSize, set real length in
xfdbi_SourceBufLen. If reading fails, goto 6.
4. Call xfdRecogBuffer(). If not successful, file is not crunched.
Go on with 6 then.
5. Print information about cruncher or something similar.
6. If you have another file to test, step back to 3.
7. Release memory of xfdbi_SourceBuffer.
8. Call xfdFreeObject() (V36).
9. Exit!
If you want to unlink two files, do it like this:
1. Call xfdAllocObject() with XFDOBJ_LINKERINFO (V36). If not successful,
go on with 9.
2. Get file size, allocate buffer with that size and load file to buffer.
If not successful, go on with 7.
3. Call xfdRecogLinker() with xfdli_Buffer and xfdli_BufLen initialized.
If not successful, file is not linked. Go on with 6 then.
4. Call xfdUnlink(). If not successful, go on with 6.
5. Do something with unlinked files.
6. Release memory of xfdli_Buffer.
7. If you have another file to unlink, step back to 2.
8. Call xfdFreeObject() (V36).
9. Exit!
If you only want to test if a file is a linked one without unlinking
it afterwards, here's a way to do this:
1. Call xfdAllocObject() with XFDOBJ_LINKERINFO (V36). If not successful,
go on with 9.
2. Get minimum buffer size for recognition from xfdm_MinLinkerSize (V36),
allocate buffer with that size and initialize xfdli_Buffer and
xfdli_BufLen. On error goto 8.
3. Read as many bytes from the file as fit in xfdli_Buffer.
If file is shorter than xfdm_MinLinkerSize, set real length in
xfdli_BufLen. If reading fails, goto 6.
4. Call xfdRecogLinker(). If not successful, file is not linked.
Go on with 6 then.
5. Print information about linker or something similar.
6. If you have another file to test, step back to 3.
7. Release memory of xfdli_Buffer.
8. Call xfdFreeObject() (V36).
9. Exit!
Whenever you intend to use a feature of the xfdmaster.library that is
marked (V34) or higher, make sure that you use this version number
during the exec.library/OpenLibrary() call. Otherwise, if you try to
use new features with an old library version, the system might crash.
xfdmaster.library/xfdAllocBufferInfo xfdmaster.library/xfdAllocBufferInfo
NAME
xfdAllocBufferInfo -- Allocate memory for BufferInfo structure.
SYNOPSIS
bufferinfo = xfdAllocBufferInfo()
D0 -30
struct xfdBufferInfo *xfdAllocBufferInfo(void);
FUNCTION
Allocates a memory block large enough to hold all information of
the xfdBufferInfo structure.
(V36) This function is obsolete and shouldn't be used with new
code any longer. Use xfdAllocObject() instead.
INPUTS
None.
RESULT
bufferinfo - Pointer to the xfdBufferInfo structure or NULL if
there occured an error.
SEE ALSO
xfdFreeBufferInfo(), xfdFreeObject()
xfdmaster.library/xfdAllocObject xfdmaster.library/xfdAllocObject
NAME
xfdAllocObject -- Allocate memory for specified object. (V36)
SYNOPSIS
object = xfdAllocObject(objecttype)
D0 -114 D0
object *xfdAllocObject(objecttype);
FUNCTION
Allocates a memory block for the specified object. Never do this in
any other way for compatibility with library updates.
INPUTS
objecttype - One of the XFDOBJ_#? types.
RESULT
object - Pointer to the object or NULL if there occured an error.
SEE ALSO
xfdFreeObject()
xfdmaster.library/xfdAllocSegmentInfo xfdmaster.library/xfdAllocSegmentInfo
NAME
xfdAllocSegmentInfo -- Allocate memory for SegmentInfo structure.
SYNOPSIS
segmentinfo = xfdAllocSegmentInfo()
D0 -42
struct xfdSegmentInfo *xfdAllocSegmentInfo(void);
FUNCTION
Allocates a memory block large enough to hold all information of
the xfdSegmentInfo structure.
(V36) This function is obsolete and shouldn't be used with new
code any longer. Use xfdAllocObject() instead.
INPUTS
None.
RESULT
segmentinfo - Pointer to the xfdSegmentInfo structure or NULL if
there occured an error.
SEE ALSO
xfdFreeSegmentInfo(), xfdFreeObject()
xfdmaster.library/xfdDecrunchBuffer xfdmaster.library/xfdDecrunchBuffer
NAME
xfdDecrunchBuffer -- Decrunch a file from buffer.
SYNOPSIS
success = xfdDecrunchBuffer(bufferinfo)
D0 -60 A0
BOOL xfdDecrunchBuffer(struct xfdBufferInfo *);
FUNCTION
Decrunches a file to a separate buffer. You have to call
xfdRecogBuffer() first, only if this call was successful,
you may call xfdDecrunchBuffer().
You have to pass the type of memory that should be used for
the target buffer in xfdbi_TargetBufMemType.
Additionally you have to init the xfdbi_Special field with
a pointer to a special info buffer if any special flags are
set in the xfdbi_PackerFlags field:
XFDPFB_PASSWORD - Buffer contains password (max. length of
password is stored in xfdbi_MaxSpecialLen,
if this is -1, password is not limited).
XFDPFB_KEY16 (V35) - xfdbi_Special points to an UWORD that holds
a 16 bit key.
XFDPFB_KEY32 (V35) - xfdbi_Special points to an ULONG that holds
a 32 bit key.
If the decrunching was successful, the following fields in
the xfdBufferInfo structure will be initialized:
xfdbi_TargetBuffer - Pointer to decrunched file buffer.
xfdbi_TargetBufSaveLen - Length of decrunched file (for saving etc.).
xfdbi_TargetBufLen - Total length of allocated buffer.
xfdbi_DecrAddress - If XFDPFB_ADDR is set in xfdbi_PackerFlags,
this contains the address where the crunched
file has been relocated to.
xfdbi_JmpAddress - If XFDPFB_ADDR is set in xfdbi_PackerFlags,
this contains the address where to jump at
in order to run the file.
INPUTS
bufferinfo - Pointer to an initialized xfdBufferInfo structure:
xfdbi_TargetBufMemType - Type of memory for target buffer.
xfdbi_Special - Pointer to special info if required.
RESULT
success - TRUE if decrunching was successful, FALSE if
anything went wrong.
NOTE
xfdDecrunchBuffer() allocates a buffer for the decrunched file,
but it doesn't release this memory afterwards. That is because
you first have to work with the decrunched file (what else?).
Therefore you have to do a call to exec.library/FreeMem() after
you finished work. Use the following parameters:
xfdbi_TargetBufLen - Lenght of buffer.
xfdbi_TargetBuffer - Pointer to buffer.
Don't forget:
xfdbi_TargetBufLen contains the length of the allocated memory
area, xfdbi_TargetBufSaveLen the length of the decrunched file
in that buffer.
xfdDecrunchBuffer() never touches the buffer that contains the
crunched file. It's again your task to release this after
decrunching.
SEE ALSO
xfdRecogBuffer(), exec.library/FreeMem()
xfdmaster.library/xfdDecrunchSegment xfdmaster.library/xfdDecrunchSegment
NAME
xfdDecrunchSegment -- Decrunch a file from its segment list.
SYNOPSIS
success = xfdDecrunchSegment(segmentinfo)
D0 -72 A0
BOOL xfdDecrunchSegment(struct xfdSegmentInfo *);
FUNCTION
Decrunches a segment list. You have to call xfdRecogSegment()
first, only if this call was successful, you may call
xfdDecrunchSegment().
You have to init the xfdsi_Special field with a pointer to a
special info buffer if any special flags are set in the
xfdsi_PackerFlags field:
XFDPFB_PASSWORD - Buffer contains password (max. length of
password is stored in xfdsi_MaxSpecialLen,
if this is -1, password is not limited).
XFDPFB_KEY16 (V35) - xfdsi_Special points to an UWORD that holds
a 16 bit key.
XFDPFB_KEY32 (V35) - xfdsi_Special points to an ULONG that holds
a 32 bit key.
(V34) Check xfdsi_Packerflags for XFDPFB_RELMODE. If set,
initialize xfdsi_RelMode with the desired XFDREL_#? value.
If decrunching was successful, xfdsi_SegList holds a BPTR to
the decrunched segment list. The old segment list has been
released and/or replaced by the new one (depends on cruncher).
If decrunching failed, xfdsi_SegList may be NULL. This happens
if an error occured after the seglist has already been changed
in any way. It then will be released.
Otherwise, if xfdsi_SegList is not NULL, it still contains a
valid BPTR to the crunched segment list.
INPUTS
segmentinfo - Pointer to an initialized xfdSegmentInfo structure:
xfdsi_Special - Pointer to special info if required.
xfdsi_RelMode - (V34) XFDREL_#? value if required.
RESULT
success - TRUE if decrunching was successful, FALSE if
anything went wrong.
NOTE
If you no longer need the decrunched segment list, you may
release it by simply calling dos.library/UnloadSeg().
SEE ALSO
xfdRecogSegment(), dos.library/UnloadSeg()
xfdmaster.library/xfdFreeBufferInfo xfdmaster.library/xfdFreeBufferInfo
NAME
xfdFreeBufferInfo -- Free memory of xfdBufferInfo structure.
SYNOPSIS
xfdFreeBufferInfo(bufferinfo)
-36 A1
void xfdFreeBufferInfo(struct xfdBufferInfo *);
FUNCTION
Deallocates the memory reserved via xfdAllocBufferInfo().
(V36) This function is obsolete and shouldn't be used with new
code any longer. Use xfdFreeObject() instead.
INPUTS
bufferinfo - Pointer to xfdBufferInfo structure.
RESULT
None.
SEE ALSO
xfdAllocBufferInfo(), xfdAllocObject()
xfdmaster.library/xfdFreeObject xfdmaster.library/xfdFreeObject
NAME
xfdFreeObject -- Free memory of object. (V36)
SYNOPSIS
xfdFreeObject(object)
-120 A1
void xfdFreeObject(object *);
FUNCTION
Deallocates the memory reserved via xfdAllocObject().
INPUTS
object - Pointer to object.
RESULT
None.
SEE ALSO
xfdAllocObject()
xfdmaster.library/xfdFreeSegmentInfo xfdmaster.library/xfdFreeSegmentInfo
NAME
xfdFreeSegmentInfo -- Free memory of xfdSegmentInfo structure.
SYNOPSIS
xfdFreeSegmentInfo(segmentinfo)
-48 A1
void xfdFreeSegmentInfo(struct xfdSegmentInfo *);
FUNCTION
Deallocates the memory reserved via xfdAllocSegmentInfo().
(V36) This function is obsolete and shouldn't be used with new
code any longer. Use xfdFreeObject() instead.
INPUTS
segmentinfo - Pointer to xfdSegmentInfo structure.
RESULT
None.
SEE ALSO
xfdAllocSegmentInfo(), xfdAllocObject()
xfdmaster.library/xfdGetErrorText xfdmaster.library/xfdGetErrorText
NAME
xfdGetErrorText -- Get an ascii string from an error number.
SYNOPSIS
string = xfdGetErrorText(error)
D0 -78 D0.w
STRPTR xfdGetErrorText(UWORD);
FUNCTION
Whenever a library call fails, you receive an error number either
in the xfd#?_Error field or directly as a returncode. This function
gets the corresponding ascii string to the occured error.
INPUTS
error - Error number from xfd#?_Error or returncode.
RESULT
string - Pointer to an ascii string that describes the error.
xfdmaster.library/xfdRecogBuffer xfdmaster.library/xfdRecogBuffer
NAME
xfdRecogBuffer -- Examine buffer for crunched file.
SYNOPSIS
success = xfdRecogBuffer(bufferinfo)
D0 -54 A0
BOOL xfdRecogBuffer(struct xfdBufferInfo *);
FUNCTION
Examines a file for known crunchers. You pass a pointer to
the file buffer in xfdbi_SourceBuffer and the length of the
buffer in xfdbi_SourceBufLen.
If a crunched file has been recognized, the following fields
in the xfdBufferInfo structure will be initialized:
xfdbi_PackerName - Pointer to the name of the cruncher.
xfdbi_PackerFlags - Contains the packer type and additional
information (eg. password).
xfdbi_MaxSpecialLen - Only used if any special flags are set.
INPUTS
bufferinfo - Pointer to an initialized xfdBufferInfo structure:
xfdbi_SourceBuffer - Pointer to file buffer.
xfdbi_SourceBufLen - Length of file buffer.
RESULT
success - TRUE if a cruncher has been recognized, FALSE if
file is unknown.
SEE ALSO
xfdDecrunchBuffer()
xfdmaster.library/xfdRecogLinker xfdmaster.library/xfdRecogLinker
NAME
xfdRecogLinker -- Examine buffer for linked file. (V36)
SYNOPSIS
success = xfdRecogLinker(linkerinfo)
D0 -126 A0
BOOL xfdRecogLinker(struct xfdLinkerInfo *);
FUNCTION
Examines a file for known link mechanisms. You pass a pointer to
the file buffer in xfdli_Buffer and the length of the buffer in
xfdli_BufLen.
If a linked file has been recognized, the following fields
in the xfdLinkerInfo structure will be initialized:
xfdli_LinkerName - Pointer to the name of the linker.
INPUTS
linkerinfo - Pointer to an initialized xfdLinkerInfo structure:
xfdli_Buffer - Pointer to file buffer.
xfdli_BufLen - Length of file buffer.
RESULT
success - TRUE if a linker has been recognized, FALSE if
file is unknown.
SEE ALSO
xfdUnlink()
xfdmaster.library/xfdRecogSegment xfdmaster.library/xfdRecogSegment
NAME
xfdRecogSegment -- Examine segment list for crunched file.
SYNOPSIS
success = xfdRecogSegment(segmentinfo)
D0 -66 A0
BOOL xfdRecogSegment(struct xfdSegmentInfo *);
FUNCTION
Examines a segment list for known crunchers. You pass a BPTR
to the segment list in xfdsi_SegList.
If a crunched segment list has been recognized, the following
fields in the xfdSegmentInfo structure will be initialized:
xfdsi_PackerName - Pointer to the name of the cruncher.
xfdsi_PackerFlags - Contains the packer type and additional
information (eg. password).
xfdsi_MaxSpecialLen - Only used if any special flags are set.
INPUTS
segmentinfo - Pointer to an initialized xfdSegmentInfo structure:
xfdsi_SegList - BPTR to segment list.
RESULT
success - TRUE if a cruncher has been recognized, FALSE if
segment list is unknown.
SEE ALSO
xfdDecrunchSegment()
xfdmaster.library/xfdRelocate xfdmaster.library/xfdRelocate
NAME
xfdRelocate -- Create segment list from file buffer. (V34)
SYNOPSIS
error = xfdRelocate(buffer, length, result, mode)
D0.w -96 A0 D0 A1 D1.w
UWORD xfdRelocate(APTR, ULONG, ULONG *, UWORD);
FUNCTION
Creates a relocated and fully executable segment list from
a file buffer. The result is a BPTR to the first segment,
similar to the result of a call to dos.library/LoadSeg().
INPUTS
buffer - Pointer to the file buffer that should be relocated.
length - Length of the file buffer.
result - Pointer to the longword that should hold the result.
mode - Any XFDREL_#? relocation mode.
RESULT
error - XFDERR_OK if no error occured, else XFDERR_#?.
result - Holds a BPTR to the first segment if error = XFDERR_OK.
NOTE
There is no need to call xfdTestHunkStructure[New|Flags]() before
relocation because xfdRelocate() does this already.
This routine supports the following hunk types:
- hunk_name ($3e8) -> Skipped.
- hunk_code ($3e9) -> Creates new code segment.
- hunk_data ($3ea) -> Creates new data segment.
- hunk_bss ($3eb) -> Creates new bss segment.
- hunk_reloc32 ($3ec) -> Used for relocation.
- hunk_symbol ($3f0) -> Skipped.
- hunk_debug ($3f1) -> Skipped.
- hunk_end ($3f2) -> May be left out.
- hunk_header ($3f3) -> Only at top of file.
- hunk_reloc32short ($3f7/$3fc) -> Used for relocation.
Any other hunk types create an error. There is no support for
hunk_overlay, because the main purpose of this routine is to
be called from xfds_DecrunchSegment. And in that case, the real
dos.library/LoadSeg() has already initialized the overlay header.
xfdmaster.library/xfdStripHunks xfdmaster.library/xfdStripHunks
NAME
xfdStripHunks -- Remove annoying hunks from file buffer. (V36)
SYNOPSIS
error = xfdStripHunks(buffer, length, result, flags)
D0.w -108 A0 D0 A1 D1.w
UWORD xfdStripHunks(APTR, ULONG, ULONG *, UWORD);
FUNCTION
Strips hunk_name, hunk_symbol and hunk_debug from file buffer.
This might be useful to shorten executables, but the main
purpose is to remove decrunch protections based on modified
hunk structures.
INPUTS
buffer - Pointer to the file buffer that should be stripped.
length - Length of the file buffer.
result - Pointer to the longword that should hold the new
file length after stripping.
flags - One or more XFDSHB_#? strip flags.
RESULT
error - XFDERR_OK if no error occured, else XFDERR_#?.
result - Holds new length of file if error = XFDERR_OK.
NOTE
There is no need to call xfdTestHunkStructure[New|Flags]() before
stripping because xfdStripHunks() does this already.
Attention! The new file length given as a result may be used
to save the modified file to disk, but the length of the
buffer itself is still the same as it was before the call.
This routine supports the following hunk types:
- hunk_name ($3e8) -> Stripped on XFDSHB_NAME.
- hunk_code ($3e9) -> Skipped.
- hunk_data ($3ea) -> Skipped.
- hunk_bss ($3eb) -> Skipped.
- hunk_reloc32 ($3ec) -> Skipped.
- hunk_symbol ($3f0) -> Stripped on XFDSHB_SYMBOL.
- hunk_debug ($3f1) -> Stripped on XFDSHB_DEBUG.
- hunk_end ($3f2) -> Skipped.
- hunk_header ($3f3) -> Only at top of file.
- hunk_reloc32short ($3f7/$3fc) -> Skipped.
Any other hunk types create an error.
xfdmaster.library/xfdTestHunkStructure xfdmaster.library/xfdTestHunkStructure
NAME
xfdTestHunkStructure -- Test hunks of executable file.
SYNOPSIS
success = xfdTestHunkStructure(buffer, length)
D0 -84 A0 D0
BOOL xfdTestHunkStructure(APTR, ULONG);
FUNCTION
Checks an executable file for a valid hunk structure.
This is important for decrunching files, because an incomplete
or damaged file may cause a system crash.
INPUTS
buffer - Pointer to the file buffer that should be checked.
length - Length of the file buffer.
RESULT
success - TRUE if file is ok, FALSE if file is damaged.
NOTE
It is recommended to use xfdTestHunkStructureNew() instead of
this routine for a more detailed error description. Internally
both calls use the same routines, this one is only left here
for downward compatibility.
SEE ALSO
xfdTestHunkStructureNew(), xfdTestHunkStructureFlags()
xfdmaster.l/xfdTestHunkStructureFlags xfdmaster.l/xfdTestHunkStructureFlags
NAME
xfdTestHunkStructureFlags -- Test hunks of executable file. (V36)
SYNOPSIS
error = xfdTestHunkStructureFlags(buffer, length, flags)
D0.w -102 A0 D0 D1.w
UWORD xfdTestHunkStructureFlags(APTR, ULONG, UWORD);
FUNCTION
Checks an executable file for a valid hunk structure and reacts
on certain hunk types if special flags are given.
This is important for decrunching files, because an incomplete
or damaged file may cause a system crash.
INPUTS
buffer - Pointer to the file buffer that should be checked.
length - Length of the file buffer.
flags - Flags to cause special actions on certain hunk types.
These are:
XFDTHB_NOOVERLAYS - forces error on hunk_overlay.
RESULT
error - XFDERR_OK if file is ok, XFDERR_#? if file is damaged
or special flags got activated.
NOTE
You don't have to call this function before trying to decrunch
a file, because xfdDecrunchBuffer() does this already.
This hunk checker supports the following hunk types:
- hunk_name ($3e8)
- hunk_code ($3e9)
- hunk_data ($3ea)
- hunk_bss ($3eb)
- hunk_reloc32 ($3ec)
- hunk_symbol ($3f0)
- hunk_debug ($3f1)
- hunk_end ($3f2)
- hunk_header ($3f3)
- hunk_overlay ($3f5) -> forces error on XFDTHB_NOOVERLAYS
- hunk_break ($3f6)
- hunk_reloc32short ($3f7/$3fc)
It recognizes the standard hunk_overlay ($3f5) format and some
user-defined overlay types too. Anyway, it may happen that some
weird overlay hunk causes problems because there isn't any real
definition for overlays.
The hunk structure of a non-overlayed file will nevertheless
be checked 100% correctly.
SEE ALSO
xfdTestHunkStructureNew()
xfdmaster.lib/xfdTestHunkStructureNew xfdmaster.lib/xfdTestHunkStructureNew
NAME
xfdTestHunkStructureNew -- Test hunks of executable file. (V34)
SYNOPSIS
error = xfdTestHunkStructureNew(buffer, length)
D0.w -90 A0 D0
UWORD xfdTestHunkStructureNew(APTR, ULONG);
FUNCTION
Checks an executable file for a valid hunk structure.
This is important for decrunching files, because an incomplete
or damaged file may cause a system crash.
INPUTS
buffer - Pointer to the file buffer that should be checked.
length - Length of the file buffer.
RESULT
error - XFDERR_OK if file is ok, XFDERR_#? if file is damaged.
NOTE
This is actually just a call to xfdTestHunkStructureFlags()
with no flags set.
SEE ALSO
xfdTestHunkStructureFlags()
xfdmaster.library/xfdUnlink xfdmaster.library/xfdUnlink
NAME
xfdUnlink -- Unlink two files inside the same buffer. (V36)
SYNOPSIS
success = xfdUnlink(linkerinfo)
D0 -132 A0
BOOL xfdUnlink(struct xfdLinkerInfo *);
FUNCTION
Unlinks two files that have been joined by some so-called
4EB9-Linker. No new buffers are created, unlinked files are both
located inside source buffer. You have to call xfdRecogLinker()
first, only if this call was successful, you may call xfdUnlink().
If unlinking was successful, the following fields in the
xfdLinkerInfo structure will be initialized:
xfdli_Save1 - Pointer to first unlinked file.
xfdli_Save2 - Pointer to second unlinked file.
xfdli_SaveLen1 - Length of first unlinked file.
xfdli_SaveLen2 - Length of second unlinked file.
INPUTS
linkerinfo - Pointer to an initialized xfdLinkerInfo structure
as received by xfdRecogLinker().
RESULT
success - TRUE if unlinking was successful, FALSE if
anything went wrong.
NOTE
After a call to xfdUnlink(), the contents of xfdli_Buffer are
under no circumstances valid any longer. The only way to make use
of the buffer contents is via xfdli_Save1 and xfdli_Save2.
But if you have finished work with the splitted files, you have
to release exactly the memory you have allocated for xfdli_Buffer.
There exist several programs that produce the same linker output.
Some of them are very badly programmed, so if unlinking fails or
produces non-executable files, don't blame xfdmaster.library.
SEE ALSO
xfdRecogLinker()
xfdForeman/--Overview-- xfdForeman/--Overview--
The xfdForeman structure is just some kind of header for external slaves.
It protects the slaves from being executed accidentally by having a small
piece of code (moveq #-1,d0 : rts) in the first 4 bytes.
The master can identify a valid bunch of external slaves by checking the
first few bytes of the file for the foreman identification.
Finally, a foreman holds the pointer to a linked list of slaves and thus
enables the master to work with these slaves.
xfdSlave/--Overview-- xfdSlave/--Overview--
The xfdSlave structure is the heart of the whole library system. Each slave
enables the master to recognize and decrunch packed files and/or segments.
Therefore each slave contains 4 routines that are called from the master.
Pointers to these routines are stored in xfds_Recog#? and xfds_Decrunch#?.
All have one thing in common: the CPU registers D0/D1/A0/A1 are so called
scratch registers, they may change during execution, all other registers
must remain unchanged. CPU register A6 holds a pointer to the xfdMasterBase
structure. See chapters below for a description of the slave routines.
ALL SLAVE ROUTINES MUST BE REENTRANT! NEVER STORE ANY DATA IN STATIC MEMORY
AREAS, USE THE STACK OR SOME ALLOCATED MEMORY INSTEAD! REMEMBER THAT THE
ROUTINES MIGHT BE CALLED BY SEVERAL PROGRAMS AT THE SAME TIME!
The name of the packer that is supported by the slave and the flags that
describe the packer are stored in xfds_PackerName and xfds_PackerFlags.
(V36) Internal slaves all have an unique ID value stored in xfds_SlaveID.
This field should be set to NULL for external slaves.
(V36) If you have written a slave that should replace an internal one
because it's faster or otherwise enhanced, simply put the ID of the slave
to be replaced in xfds_ReplaceID. The old slave will then be taken out of
the list of used slaves. Otherwise, xfds_ReplaceID must be NULL.
(V36) xfdRecogBuffer() usually only requires a quite small part of a file
to recognize it properly. To avoid reading the whole file for recognition
purposes, you may set xfds_MinBufferSize to the minimum amount of bytes
that is required to recognize the crunched file correctly.
Note that xfdRecogBuffer() uses this value internally to decide whether
a file might be crunched with a packer or not, so you don't have to do
an extra size comparison in your xfds_RecogBuffer function any more.
For packer headers with non-constant sizes, simply set xfds_MinBufferSize
to a value that will ensure correct recognition of all possible files.
Whenever you intend to use features of the xfdmaster.library in your slaves
that are marked (V34) or higher, make sure to set xfds_MasterVersion to
the desired version number, otherwise an old library version might crash
while using the new slave.
xfdSlave/RecogBufferXYZ xfdSlave/RecogBufferXYZ
NAME
RecogBufferXYZ -- Recognize crunched file in buffer.
SYNOPSIS
result = RecogBufferXYZ(buffer, length)
D0 A0 D0
BOOL RecogBufferXYZ(APTR, ULONG);
FUNCTION
This routine should examine the buffer for a crunched file.
First thing is to check if the size of the file allows it to
be crunched with the packer in question. After that, simply
do some compares to figure out if the file has been crunched
or not.
(V36) You don't have to do any size comparisons if you set
xfds_MinBufferSize to the minimum amount of bytes that are
necessary for a file to be crunched with that packer.
INPUTS
buffer - Pointer to a buffer that holds the crunched file.
length - Length of that buffer.
RESULT
result - TRUE if packer has been recognized, else FALSE.
NOTE
You have to initialize xfds_RecogBuffer with a pointer to your
RecogBufferXYZ routine.
SEE ALSO
Example sourcecodes.
xfdSlave/DecrunchBufferXYZ xfdSlave/DecrunchBufferXYZ
NAME
DecrunchBufferXYZ -- Decrunch file from buffer to buffer.
SYNOPSIS
result = DecrunchBufferXYZ(bufferinfo)
D0 A0
BOOL DecrunchBufferXYZ(struct xfdBufferInfo *);
FUNCTION
The typical steps of such a routine are:
- Get length of decrunched file (exactly or a bit too much).
- Allocate memory (with memtype from xfdbi_TargetBufMemType).
- Decrunch file from xfdbi_SourceBuffer to xfdbi_TargetBuffer.
- Initialize all necessary parts of the xfdBufferInfo structure.
- Set xfdbi_Error if an error occurs.
INPUTS
bufferinfo - A valid xfdBufferInfo structure that successfully went
through a call to xfdRecogBuffer().
RESULT
result - TRUE if decrunching succeeded, FALSE if something went wrong.
NOTE
You have to initialize xfds_DecrunchBuffer with a pointer to your
DecrunchBufferXYZ routine.
SEE ALSO
Example sourcecodes.
xfdSlave/RecogSegmentXYZ xfdSlave/RecogSegmentXYZ
NAME
RecogSegmentXYZ -- Recognize crunched segment list.
SYNOPSIS
result = RecogSegmentXYZ(seglist)
D0 A0
BOOL RecogSegmentXYZ(BPTR);
FUNCTION
This routine should examine if a segment list is crunched.
You can check the whole segment list for correct lengths of hunks
and for contents of hunks if you like. There should be at least
3 comparations to determine the cruncher.
INPUTS
seglist - BPTR to first segment.
RESULT
result - TRUE if packer has been recognized, else FALSE.
NOTE
You have to initialize xfds_RecogSegment with a pointer to your
RecogSegmentXYZ routine.
SEE ALSO
Example sourcecodes.
xfdSlave/DecrunchSegmentXYZ xfdSlave/DecrunchSegmentXYZ
NAME
DecrunchSegmentXYZ -- Decrunch segment list.
SYNOPSIS
result = DecrunchSegmentXYZ(segmentinfo)
D0 A0
BOOL DecrunchSegmentXYZ(struct xfdSegmentInfo *);
FUNCTION
There are two possibilities how to decrunch a segment list. The
first one works like this:
- Modify decrunch header to make it return to the caller.
- Call decrunch header.
- dos.library/UnloadSeg() whole seglist and clear xfdsi_SegList
if an error occurs and the seglist has already been altered
in any way.
- Otherwise only release segments that are no longer necessary.
- Store BPTR to first hunk of decrunched segment list in
xfdsi_SegList.
- Set xfdsi_Error if an error occurs.
The second possibility works the same way as the first with
the difference that you don't jump to the original code, but you
include all necessary parts of it (decrunch routine, relocator)
in your own routine. The big advantage is that you can handle
error conditions much better because most of the standard decrunch
headers in executable files have problems with low memory etc.
(V34) If the decruncher allows it, always support XFDPFB_RELMODE.
That way the caller can determine the type of memory the segments
should be placed in by initializing xfdsi_RelMode with XFDREL_#?.
Many crunchers don't change the hunk structure of the crunched
data. If this is the case, you can simply call the decrunch code
in the segment list and then use xfdRelocate() (V34).
INPUTS
segmentinfo - A valid xfdSegmentInfo structure that successfully went
through a call to xfdRecogSegment().
RESULT
result - TRUE if decrunching succeeded, FALSE if something went wrong.
NOTE
You have to initialize xfds_DecrunchSegment with a pointer to your
DecrunchSegmentXYZ routine.
SEE ALSO
Example sourcecodes.